/*
 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.nio.channels;

import java.io.IOException;
import java.nio.ByteBuffer;


/**
 * 一个可以写入字节的通道。
 *
 * <p> 在任何给定的时间内，在可写通道上只能进行一个写操作。
 * 如果一个线程在一个通道上启动了一个写操作，那么任何其他尝试启动另一个写操作的线程都会阻塞，直到第一个操作完成。
 * 其他类型的I/O操作是否可以与写操作同时进行，取决于通道的类型。</p>
 *
 *
 * @author Mark Reinhold
 * @author JSR-51 Expert Group
 * @since 1.4
 */

public interface WritableByteChannel
    extends Channel
{

    /**
     * 将一个字节序列从给定的缓冲区写入此通道。
     *
     * <p> 尝试将最多r字节写入到通道，其中r是在调用此方法时缓冲区中剩余的字节数，即src.remaining()。
     *
     * <p> 假设写入了一个长度为n的字节序列，其中0 <= n <= r。
     * 这个字节序列将从索引p开始的缓冲区中传输，其中p是调用此方法时缓冲区的位置;
     * 最后一个字节的索引将是p + n - 1。
     * 返回后，缓冲区的位置将等于p + n;它的极限不会改变。
     *
     * <p> 除非另有规定，写操作只会在写完所有r请求的字节后返回。
     * 某些类型的通道，取决于它们的状态，可能只写一些字节，也可能根本不写。
     * 例如，在非阻塞模式下的套接字通道不能发送比套接字输出缓冲区中空闲的字节更多的字节。
     *
     * <p> 此方法可以在任何时候调用。
     * 但是，如果另一个线程已经在这个通道上启动了写操作，那么对这个方法的调用将阻塞，直到第一个操作完成。</p>
     *
     * @param  src
     *         The buffer from which bytes are to be retrieved
     *
     * @return The number of bytes written, possibly zero
     *
     * @throws  NonWritableChannelException
     *          If this channel was not opened for writing
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     *
     * @throws  AsynchronousCloseException
     *          If another thread closes this channel
     *          while the write operation is in progress
     *
     * @throws  ClosedByInterruptException
     *          If another thread interrupts the current thread
     *          while the write operation is in progress, thereby
     *          closing the channel and setting the current thread's
     *          interrupt status
     *
     * @throws  IOException
     *          If some other I/O error occurs
     */
    public int write(ByteBuffer src) throws IOException;

}
